System Contract Introduction

Author: fisco-dev

• FISCO BCOS System Contract Introduction
  • Design Overview
  • How it works
    • System Proxy
    • Node Management
    • CA Management
    • Permissions Management
    • Configuration Management
  • Customizations
    • Example 1 - Custom Business Contract
    • Example 2 - Custom Permission Contract

Design Overview

In order to meet the requirements of access control, identity authentication, configuration management and permissions management etc., FISCO BCOS will deploy a set of powerful, flexible, and custom-defined smart contracts during the network initialization, collectively referred to as system contracts.

The system contract is deployed by administrator during initialization. For redeploying any changes or upgrades while the network is running, it is necessary for the blockchain administrator to get an agreement of all the nodes within the network.

FISCO BCOS system contract is comprised of five modules: System Proxy, Node Management, CA Management, Permissions Management and Configuration Management. System contracts is extendable and can be called by both core system and DAPP. There could be one or more smart contracts in a module. The modules are as below:

module structure

How it works

Code path: systemcontractv2/. Brief of each module is as below:

System Proxy

SystemProxy.sol, the system proxy’s implementation, provides a mapping between route and contract address, unified system contract interface. In SystemProxy.sol, routing info is held by a mapping field, named as ‘_routes’. The value of mapping is structured as below:

struct SystemContract {
    address _addr;		#contract address
    bool _cache;		#cache flag
    uint _blocknumber;		#block height when the contract is active
}

Key functions:

function	input parameters	output parameters	description
getRoute	string key#route name	address#contract address, bool#catch flag, uint # block height	get route information
setRoute	string key#route name, address addr#contract address, bool cache#cache flag, unit blocknumber #block height	N/A	set route, overwrite if route name exists

Node Management

NodeAction.sol is the implementation contract of the node management module. It implements the function of registering, managing and maintaining the list information of all nodes in the network. Every time a node in the network joins or quits, it must controlled by the node management contract. Three node types: Core, Full, and Light.

enum NodeType{
        None,
        Core,
        Full,
        Light
    }

Structure for node information:

struct NodeInfo{
        string id;
        string ip;
        uint port;
        NodeType category;
        string desc;
        string CAhash;
        string agencyinfo;
        uint idx;
        uint blocknumber;       #block height
    }

Key functions:

function	input parameters	output parameters	description
registerNode	string _id string _ip uint _port NodeType _category string _desc string _CAhash string _agencyinfo uint _idx	bool #result	register node Ignore if the node exists
cancelNode	string _id	bool #result	cancel node Ignore if the node not exists

CA Management

CAAction.sol is the implementation contract of the CA management module. It provides nodes’ certificate registration, management and maintenance. Node joins or quits the chain must controlled by CA management contract if certificate verification enabled.

Structure for certificate data:

struct CaInfo{
        string  hash;		#certificate hash
        string pubkey;		#certificate public key
        string orgname;		#organization name
        uint notbefore;		#certificate effective date
        uint notafter;		#certificate expire date
        CaStatus status;	#certificate status
        string    whitelist;	#IP whitelist
        string    blacklist;	#IP blacklist
        uint    blocknumber;	#block height
      }

Key functions:

function	input parameters	output parameters	description
update	string _hash string _pubkey string _orgname uint _notbefore uint _notafter CaStatus _status string _whitelist string _blacklist	bool #result	update certificate create certificate if certificate not exists
get	string _hash	string#certificate hash string#certificate public key string#organization name uint#certificate effective date uint#certificate expire date CaStatus#certificate status uint##block height	get certificate information

Permissions Management

Permissions management’s design principles: 1, One external account only belongs to one role. 2, One role only has one permission list. 3, Permission is identified by a combination of function and its contract address.

Permission module are comprised of 4 contracts: TransactionFilterChain.sol, TransactionFilterBase.sol, AuthorityFilter.sol, Group.sol.

TransactionFilterChain.sol, the implementation of Filter pattern, provides a unified function ‘process’ for permission checking. It holds an address list of Filter contract which extends from TransactionFilterBase. All permissions will be checked by the calling ‘process’ function of each Filter contract sequentially.

All Filters must implement TransactionFilterBase’s ‘process’ interface, AuthorityFilter is inherited from TransactionFilterBase’s role permission Filter implementation. Its process interface implements the checking logic for the permissions of the user role groups.

Group.sol handles the concept of Role. It internally maintains the mapping flag for all permission entries for this role.

Key functions:

contract	function	input parameters	output parameters	description
TransactionFilterBase	process	address origin #external address address from#from account address address to#to account address string func#contract address string input#transaction input	bool#result	permission checking
Group	setPermission	address to#to account address string func#contract address bool permission#permission flag	bool#result	set permission

Configuration Management

ConfigAction.sol is the implementation of configuration management module for entire network. It maintains configurable information for the entire network in the FISCO BCOS blockchain. The configuration information is kept consistent through out the entire network by transactions broadcast. In principle, only the blockchain administrator can issue transactions broadcast to perform network-wide configuration changes.

Key functions:

function	input parameters	output parameters	description
set	string key #parameter string value#config information value	N/A	set configuration
get	string key #parameter	string #config information uint#block height	get configuration

key parameters:

parameter	description	default value	recommend value
maxBlockHeadGas	Gas spend limitation for each block (Hex)	200000000	20000000000
intervalBlockTime	an interval btw block generation(ms) (Hex)	1000	1000
maxBlockTranscations	configure the max transaction in a block(Hex)	1000	1000
maxNonceCheckBlock	Trace back max previous block number to avoid nonce duplication.(Hex)	1000	1000
maxBlockLimit	max delay for transaction commit(Hex)	1000	1000
maxTranscationGas	Gas spend limitation for each transaction(Hex)	20000000	20000000
CAVerify	CA verification flag	FALSE	FALSE

Customizations

Example 1 - Custom Business Contract

To customize a business contract by modifying business configuration. Refer to the steps below:

1. Implement ‘set’ and ‘get’ based on business requirement.
2. Deploy business contract and get contract address.
3. Call the ‘setRoute’ method in SystemProxy to register contract address in the routing table.
4. Business smart contract is now ready to be called.

How to call the business contract:

1. Call the ‘getRoute’ method in SystemProxy to get the contract address.
2. Get configured information by calling the ‘get’ method with address in step 1.

Example 2 - Custom Permission Contract

Permission checking can be extended by adding new Filter. Refer to the steps below:

1. Create a Filter permission contract by inheriting TransactionFilterBase. The custom permissions verification logic should be implemented into the ‘process’ interface as per the business requirements.
2. Deploy custom permission contract and get contract address.
3. Call the ‘getRoute’ method in SystemProxy to get contract address of TransactionFilterChain.
4. Register custom filter contract by calling ‘addFilter’ method in TransactionFilterChain.
5. The contract is now ready for calling.